---
{
	"title": "Menu",
	"language": "en",
	"category": "Plugins",
	"categoryfile": "plugins",
	"description": "Provides an interactive menu with optional sub-menus.",
	"altLangPrefix": "menu",
	"dateModified": "2017-06-12"
}
---
<span class="wb-prettify all-pre hide"></span>

<section>
	<h2>Purpose</h2>
	<p>Provides an interactive menu with optional sub-menus. Implements the <a href="https://www.w3.org/TR/wai-aria-practices/#menu">WAI-ARIA menu design pattern</a>.</p>
</section>

<section>
	<h2>Working example</h2>
	<ul>
		<li><a href="../../../demos/menu/menu-en.html">English example</a></li>
		<li><a href="../../../demos/menu/menu-fr.html">French example</a></li>
		<li><a href="../../../demos/menu/footer-menu-en.html">Footer Menu Integration - English</a></li>
		<li><a href="../../../demos/menu/footer-menu-fr.html">Footer Menu Integration - Français</a></li>
	</ul>
</section>

<section>
	<h2>How to implement</h2>
	<ol>
		<li>Add the following code to the <code>header</code> area of the page. <strong>Note:</strong> This step should already be done for most themes.
			<ul>
				<li><strong>English pages:</strong>
					<pre><code>&lt;nav role="navigation" id="wb-sm" data-trgt="mb-pnl" class="wb-menu visible-md visible-lg" typeof="SiteNavigationElement"&gt;
	&lt;div class="container nvbar"&gt;
		&lt;h2&gt;Topics menu&lt;/h2&gt;
		&lt;div class="row"&gt;
			&lt;ul class="list-inline menu"&gt;
				&lt;li&gt;&lt;a href="#"&gt;Section 1&lt;/a&gt;&lt;/li&gt;
				&lt;li&gt;&lt;a href="#"&gt;Section 2&lt;/a&gt;&lt;/li&gt;
				&lt;li&gt;&lt;a href="#"&gt;Section 3&lt;/a&gt;&lt;/li&gt;
			&lt;/ul&gt;
		&lt;/div&gt;
	&lt;/div&gt;
&lt;/nav&gt;</code></pre>
				</li>
				<li><strong>French pages:</strong>
					<pre><code>&lt;nav role="navigation" id="wb-sm" data-trgt="mb-pnl" class="wb-menu visible-md visible-lg" typeof="SiteNavigationElement"&gt;
	&lt;div class="container nvbar"&gt;
		&lt;h2&gt;Menu des sujets&lt;/h2&gt;
		&lt;div class="row"&gt;
			&lt;ul class="list-inline menu"&gt;
				&lt;li&gt;&lt;a href="#"&gt;Section 1&lt;/a&gt;&lt;/li&gt;
				&lt;li&gt;&lt;a href="#"&gt;Section 2&lt;/a&gt;&lt;/li&gt;
				&lt;li&gt;&lt;a href="#"&gt;Section 3&lt;/a&gt;&lt;/li&gt;
			&lt;/ul&gt;
		&lt;/div&gt;
	&lt;/div&gt;
&lt;/nav&gt;</code></pre>
				</li>
			</ul>
		</li>
		<li>Update the <code>ul</code> element with list items (<code>li</code>) containing the desired links.</li>
		<li><strong>Optional:</strong> Create a full menu to AJAX in. This menu will replace the <code>class="container"</code> element and its descendants. Sub-menus are achieved by nesting <code>&lt;ul class="sm list-unstyled" id="lore" role="menu"&gt;</code> in each <code>li</code> element of the menu bar. The following is an example of a full menu:
			<ul>
				<li><strong>English pages:</strong>
					<pre><code>&lt;div class="pnl-strt container visible-md visible-lg nvbar"&gt;
	&lt;h2&gt;Topics menu&lt;/h2&gt;
	&lt;div class="row"&gt;
		&lt;ul class="list-inline menu" role="menubar"&gt;
			&lt;li&gt;&lt;a href="#lore" class="item"&gt;Section 1&lt;/a&gt;
				&lt;ul class="sm list-unstyled" id="lore" role="menu"&gt;
					&lt;li&gt;&lt;a href="#"&gt;Item 1.1&lt;/a&gt;&lt;/li&gt;
					...
				&lt;/ul&gt;
			&lt;/li&gt;
			&lt;li&gt;&lt;a href="#lor" class="item"&gt;Section 2&lt;/a&gt;
				&lt;ul class="sm list-unstyled" id="lor" role="menu" &gt;
					&lt;li&gt;&lt;a href="#"&gt;Item 2.1&lt;/a&gt;&lt;/li&gt;
					...
					&lt;li class="slflnk"&gt;&lt;a href="#"&gt;Section 2 - More&lt;/a&gt;&lt;/li&gt;
				&lt;/ul&gt;
			&lt;/li&gt;
			&lt;li&gt;&lt;a href="#lorm" class="item"&gt;Section 3&lt;/a&gt;
				&lt;ul class="sm list-unstyled" id="lorm" role="menu" &gt;
					&lt;li&gt;
						&lt;details&gt;
							&lt;summary&gt;Section 3.1&lt;/summary&gt;
							&lt;ul role="menu"&gt;
								&lt;li&gt;&lt;a href="#"&gt;Item 3.1.1&lt;/a&gt;&lt;/li&gt;
								...
							&lt;/ul&gt;
						&lt;/details&gt;
					&lt;/li&gt;
					...
				&lt;/ul&gt;
			&lt;/li&gt;
		&lt;/ul&gt;
	&lt;/div&gt;
&lt;/div&gt;</code></pre>
				</li>
				<li><strong>French pages:</strong>
					<pre><code>&lt;div class="pnl-strt container visible-md visible-lg nvbar"&gt;
	&lt;h2&gt;Menu des sujets&lt;/h2&gt;
	&lt;div class="row"&gt;
		&lt;ul class="list-inline menu" role="menubar"&gt;
			&lt;li&gt;&lt;a href="#lore" class="item"&gt;Section 1&lt;/a&gt;
				&lt;ul class="sm list-unstyled" id="lore" role="menu"&gt;
					&lt;li&gt;&lt;a href="#"&gt;Article 1.1&lt;/a&gt;&lt;/li&gt;
					...
				&lt;/ul&gt;
			&lt;/li&gt;
			&lt;li&gt;&lt;a href="#lor" class="item"&gt;Section 2&lt;/a&gt;
				&lt;ul class="sm list-unstyled" id="lor" role="menu" &gt;
					&lt;li&gt;&lt;a href="#"&gt;Article 2.1&lt;/a&gt;&lt;/li&gt;
					...
					&lt;li class="slflnk"&gt;&lt;a href="#"&gt;Section 2 - Autre&lt;/a&gt;&lt;/li&gt;
				&lt;/ul&gt;
			&lt;/li&gt;
			&lt;li&gt;&lt;a href="#lorm" class="item"&gt;Section 3&lt;/a&gt;
				&lt;ul class="sm list-unstyled" id="lorm" role="menu" &gt;
					&lt;li&gt;
						&lt;details&gt;
							&lt;summary&gt;Section 3.1&lt;/summary&gt;
							&lt;ul role="menu"&gt;
								&lt;li&gt;&lt;a href="#"&gt;Article 3.1.1&lt;/a&gt;&lt;/li&gt;
								...
							&lt;/ul&gt;
						&lt;/details&gt;
					&lt;/li&gt;
					...
				&lt;/ul&gt;
			&lt;/li&gt;
		&lt;/ul&gt;
	&lt;/div&gt;
&lt;/div&gt;</code></pre>
				</li>
			</ul>
		</li>
		<li><strong>Optional:</strong> Add sub-sub-menus to the full menu using nested <code>details</code> elements.<br><strong>Warning:</strong> Sub-sub-menus significantly increase menu complexity, particularly on screen readers and mobile devices, which can create usability issues for some users.
			<pre><code>&lt;ul class="sm list-unstyled" id="lorm" role="menu" &gt;
	&lt;li&gt;
		&lt;details&gt;
			&lt;summary&gt;Section 3.1&lt;/summary&gt;
			&lt;ul role="menu"&gt;
				&lt;li&gt;&lt;a href="#"&gt;Item 3.1.1&lt;/a&gt;&lt;/li&gt;
					...
			&lt;/ul&gt;
		&lt;/details&gt;
	&lt;/li&gt;
	...
&lt;/ul&gt;</code></pre>
		</li>
		<li><strong>Optional:</strong> Add <code>data-ajax-replace="[url]"</code> to the element with <code>class="wb-menu"</code>, with <code>[url]</code> being the URL of the full menu to AJAX in.
			<pre><code>&lt;nav role="navigation" id="wb-sm" data-ajax-replace="ajax/menu-include-en.html" data-trgt="mb-pnl" class="wb-menu visible-md visible-lg" typeof="SiteNavigationElement"&gt;</code></pre>
		</li>
		<li><strong>Optional:</strong> Update <code>data-trgt</code> with the <code>id</code> of the target element for the mobile panel (in most cases this should not change).</li>
	</ol>
</section>

<section id="footer-doc">
	<h2>Footer Integration in Mobile Menu</h2>
	<p>For small and medium sized screens, the menu is rendered as a side panel, triggered by a menu button in the header, and includes the secondary menu and the footer. Footer sections must follow supported design patterns to be rendered in the menu without issue.</p>
	<section>
		<h2 class="mrgn-tp-0 text-success h4">Supported <span class="glyphicon glyphicon-ok-circle"></span></h2>
		<div class="accordion">
			<details class="acc-group">
				<summary class="wb-toggle tgl-tab" data-toggle='{"parent": ".accordion", "group": ".acc-group"}'>Heading followed by a list of links</summary>
				<div class="tgl-panel">
					<section>
						<h3>Purpose</h3>
						<p>Use a heading followed by a list when multiple links need to be displayed. In the menu panel, this is rendered as a <code>&lt;details&gt;</code> element, with the heading as a summary.</p>
					</section>
					<section>
						<h3>Code</h3>
						<pre><code>&lt;section class="col-sm-4"&gt;
	&lt;h3&gt;Heading 1&lt;/h3&gt;
	&lt;ul class="list-unstyled"&gt;
		&lt;li&gt;&lt;a href="#"&gt;List Element 1.1&lt;/a&gt;&lt;/li&gt;
		&lt;li&gt;&lt;a href="#"&gt;List Element 1.2&lt;/a&gt;&lt;/li&gt;
	&lt;/ul&gt;
&lt;/section&gt;</code></pre>
					</section>
				</div>
			</details>

			<details class="acc-group">
				<summary class="wb-toggle tgl-tab" data-toggle='{"parent": ".accordion", "group": ".acc-group"}'>Heading followed by a single link</summary>
				<div class="tgl-panel">
					<section>
						<h3>Purpose</h3>
						<p>A heading followed by a single link, either on its own or in a paragraph. In the menu panel, this is rendered as a single menu item, with the heading as the text.</p>
					</section>

					<section>
						<h3>Code</h3>
					<pre><code>&lt;section class="col-sm-4"&gt;
	&lt;h3&gt;Heading 1&lt;/h3&gt;
	&lt;p&gt;&lt;a href="#"&gt;Link 1&lt;/a&gt;&lt;/p&gt;
&lt;/section&gt;</code></pre>
					</section>
				</div>
			</details>

			<details class="acc-group">
				<summary class="wb-toggle tgl-tab" data-toggle='{"parent": ".accordion", "group": ".acc-group"}'>Linked heading</summary>
				<div class="tgl-panel">
					<section>
						<h3>Purpose</h3>
							<p>A heading on its own, containing a link. In the menu panel, this is rendered as a single menu item.</p>
					</section>

					<section>
						<h3>Code</h3>
							<pre><code>&lt;section class="col-sm-4"&gt;
	&lt;h3&gt;&lt;a href="#"&gt;Heading 1&lt;/a&gt;&lt;/h3&gt;
&lt;/section&gt;</code></pre>
					</section>
				</div>
			</details>
		</div>

		<h2 class="text-danger h4">Not Supported <span class="glyphicon glyphicon-remove-circle"></span></h2>
		<div class="accordion">
			<details class="acc-group">
				<summary class="wb-toggle tgl-tab" data-toggle='{"parent": ".accordion", "group": ".acc-group"}'>Linked heading followed by a list of links</summary>
				<div class="tgl-panel">
					<section>
						<h3>Purpose</h3>
							<p>A combination of the list and lone heading pattern. This will not render properly in the menu panel, as the heading link will not be clickable.</p>
					</section>
					<section>
						<h3>Code</h3>
						<pre><code>&lt;section class="col-sm-4"&gt;
	&lt;h3&gt;&lt;a href="#"&gt;Heading 1&lt;/a&gt;&lt;/h3&gt;
	&lt;ul class="list-unstyled"&gt;
		&lt;li&gt;&lt;a href="#"&gt;List Element 1.1&lt;/a&gt;&lt;/li&gt;
		&lt;li&gt;&lt;a href="#"&gt;List Element 1.2&lt;/a&gt;&lt;/li&gt;
	&lt;/ul&gt;
&lt;/section&gt;</code></pre>
					</section>
				</div>
			</details>

			<details class="acc-group">
				<summary class="wb-toggle tgl-tab" data-toggle='{"parent": ".accordion", "group": ".acc-group"}'>Heading followed by multiple links without using a list</summary>
				<div class="tgl-panel">
					<section>
						<h3>Purpose</h3>
							<p>A heading followed by a multiple links, either on their own, in paragraphs, or in smaller headings. Only the first link will be clickable in the menu panel.</p>
					</section>

					<section>
						<h3>Code</h3>
						<pre><code>&lt;section class="col-sm-4"&gt;
	&lt;h3&gt;Heading 1&lt;/h3&gt;
	&lt;p&gt;&lt;a href="#"&gt;Link 1.1&lt;/a&gt;&lt;/p&gt;
	&lt;p&gt;&lt;a href="#"&gt;Link 1.2&lt;/a&gt;&lt;/p&gt;
&lt;/section&gt;</code></pre>
					</section>
				</div>
			</details>

			<details class="acc-group">
				<summary class="wb-toggle tgl-tab" data-toggle='{"parent": ".accordion", "group": ".acc-group"}'>Multiple linked headings</summary>
				<div class="tgl-panel">
					<section>
						<h3>Purpose</h3>
							<p>Multiple headings of the same size, each containing links. These will cause unwanted gaps in the menu panel. Additionally, this structure is not compliant to the HTML5 specification.</p>
					</section>
					<section>
						<h3>Code</h3>
						<pre><code>&lt;section class="col-sm-4"&gt;
	&lt;h3&gt;&lt;a href="#"&gt;Heading 1&lt;/a&gt;&lt;/h3&gt;
	&lt;h3&gt;&lt;a href="#"&gt;Heading 2&lt;/a&gt;&lt;/h3&gt;
&lt;/section&gt;</code></pre>
					</section>
				</div>
			</details>
		</div>
		<h2 class="text-warning h4">Be Cautious <span class="glyphicon glyphicon-exclamation-sign"></span></h2>
		<p>Mixing different supported structures will work, but it is better to be consistent and only use one.</p>
	</section>
</section>

<section>
	<h2>Configuration options</h2>
	<table class="table">
		<thead>
			<tr>
				<th>Option</th>
				<th>Description</th>
				<th>How to configure</th>
				<th>Values</th>
			</tr>
		</thead>
		<tbody>
			<tr>
				<td><code>data-ajax-replace</code></td>
				<td>Used to AJAX in a full menu.</td>
				<td>Add <code>data-ajax-replace="[url]"</code> to the element with <code>class="wb-menu"</code>, with <code>[url]</code> being the URL of the full menu to AJAX in.</td>
				<td>
					<dl>
						<dt>None (default):</dt>
						<dd>Full menu is not AJAXed in.</dd>
						<dt>URL</dt>
						<dd>URL for the full menu to AJAX in.</dd>
					</dl>
				</td>
			</tr>
			<tr>
				<td><code>data-trgt</code></td>
				<td>Used to identify the target for the mobile panel.</td>
				<td>Add <code>data-trgt="mb-pnl"</code> to the element with <code>class="wb-menu"</code>. The value of <code>data-trgt</code> must match the <code>id</code> of the target element for the mobile panel.</td>
				<td>
					<dl>
						<dt>String</dt>
						<dd>The <code>id</code> of the target element (should remain <code>mb-pnl</code> unless that <code>id</code> has changed.</dd>
					</dl>
				</td>
			</tr>
		</tbody>
	</table>
</section>

<section>
	<h2>Events</h2>
	<table class="table">
		<thead>
			<tr>
				<th>Event</th>
				<th>Trigger</th>
				<th>What it does</th>
			</tr>
		</thead>
		<tbody>
			<tr>
				<td><code>wb-init.wb-menu</code></td>
				<td>Triggered manually (e.g., <code>$( ".wb-menu" ).trigger( "wb-init.wb-menu" );</code>).</td>
				<td>Used to manually initialize the menu plugin. <strong>Note:</strong> The menu plugin will be initialized automatically unless the menu markup is added after the page has already loaded.</td>
			</tr>
			<tr>
				<td><code>wb-ready.wb-menu</code> (v4.0.5+)</td>
				<td>Triggered automatically after a menu has initialized.</td>
				<td>Used to identify which menu has initialized (target of the event).
					<pre><code>$( document ).on( "wb-ready.wb-menu", ".wb-menu", function( event, instance, settings ) {
});</code></pre>
					<pre><code>$( ".wb-menu" ).on( "wb-ready.wb-menu", function( event ) {
});</code></pre>
				</td>
			</tr>
			<tr>
				<td><code>wb-ready.wb</code> (v4.0.5+)</td>
				<td>Triggered automatically when WET has finished loading and executing.</td>
				<td>Used to identify when all WET plugins and polyfills have finished loading and executing.
					<pre><code>$( document ).on( "wb-ready.wb", function( event ) {
});</code></pre>
				</td>
			</tr>
		</tbody>
	</table>
</section>

<section>
	<h2>Source code</h2>
	<p><a href="https://github.com/wet-boew/wet-boew/tree/master/src/plugins/menu">Menu source code on GitHub</a></p>
</section>
